/**
 * ***************************************************************************** Copyright (c) 2000,
 * 2014 IBM Corporation and others. All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0 which accompanies this
 * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
 *
 * <p>Contributors: IBM Corporation - initial API and implementation
 * *****************************************************************************
 */
package org.eclipse.core.resources;

import java.net.URI;
import org.eclipse.core.runtime.*;

/**
 * A root resource represents the top of the resource hierarchy in a workspace. There is exactly one
 * root in a workspace. The root resource has the following behavior:
 *
 * <ul>
 *   <li>It cannot be moved or copied
 *   <li>It always exists.
 *   <li>Deleting the root deletes all of the children under the root but leaves the root itself
 *   <li>It is always local.
 *   <li>It is never a phantom.
 * </ul>
 *
 * <p>Workspace roots implement the <code>IAdaptable</code> interface; extensions are managed by the
 * platform's adapter manager.
 *
 * @see Platform#getAdapterManager()
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IWorkspaceRoot extends IContainer, IAdaptable {

  /**
   * Deletes everything in the workspace except the workspace root resource itself.
   *
   * <p>This is a convenience method, fully equivalent to:
   *
   * <pre>
   *   delete(
   *     (deleteContent ? IResource.ALWAYS_DELETE_PROJECT_CONTENT : IResource.NEVER_DELETE_PROJECT_CONTENT )
   *        | (force ? FORCE : IResource.NONE),
   *     monitor);
   * </pre>
   *
   * <p>This method changes resources; these changes will be reported in a subsequent resource
   * change event.
   *
   * <p>This method is long-running; progress and cancellation are provided by the given progress
   * monitor.
   *
   * @param deleteContent a flag controlling how whether content is aggressively deleted
   * @param force a flag controlling whether resources that are not in sync with the local file
   *     system will be tolerated
   * @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
   * @exception CoreException if this method fails. Reasons include:
   *     <ul>
   *       <li>A project could not be deleted.
   *       <li>A project's contents could not be deleted.
   *       <li>Resource changes are disallowed during certain types of resource change event
   *           notification. See <code>IResourceChangeEvent</code> for more details.
   *     </ul>
   *
   * @exception OperationCanceledException if the operation is canceled. Cancelation can occur even
   *     if no progress monitor is provided.
   * @see IResource#delete(int,IProgressMonitor)
   */
  public void delete(boolean deleteContent, boolean force, IProgressMonitor monitor)
      throws CoreException;

  /**
   * Returns the handles to all the resources (workspace root, project, folder) in the workspace
   * which are mapped to the given path in the local file system. Returns an empty array if there
   * are none.
   *
   * <p>If the path maps to the platform working location, the returned object will be a single
   * element array consisting of an object of type <code>ROOT</code>.
   *
   * <p>If the path maps to a project, the resulting array will contain a resource of type <code>
   * PROJECT</code>, along with any linked folders that share the same location. Otherwise the
   * resulting array will contain folders (type <code>FOLDER</code>).
   *
   * <p>The path should be absolute; a relative path will be treated as absolute. The path segments
   * need not be valid names; a trailing separator is ignored. The resulting resources may not
   * currently exist.
   *
   * <p>The result will omit team private members and hidden resources. The result will omit
   * resources within team private members or hidden containers.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * @param location a path in the local file system
   * @return the corresponding containers in the workspace, or an empty array if none
   * @since 2.1
   * @deprecated use {@link #findContainersForLocationURI(URI)} instead
   */
  @Deprecated
  public IContainer[] findContainersForLocation(IPath location);

  /**
   * Returns the handles to all the resources (workspace root, project, folder) in the workspace
   * which are mapped to the given URI. Returns an empty array if there are none.
   *
   * <p>If the path maps to the platform working location, the returned object will be a single
   * element array consisting of an object of type <code>ROOT</code>.
   *
   * <p>If the path maps to a project, the resulting array will contain a resource of type <code>
   * PROJECT</code>, along with any linked folders that share the same location. Otherwise the
   * resulting array will contain folders (type <code>FOLDER</code>).
   *
   * <p>The URI must be absolute; its segments need not be valid names; a trailing separator is
   * ignored. The resulting resources may not currently exist.
   *
   * <p>The result will omit team private members and hidden resources. The result will omit
   * resources within team private member sor hidden containers.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * <p>This is a convenience method, fully equivalent to <code>
   * findContainersForLocationURI(location, IResource.NONE)</code>.
   *
   * @param location a URI path into some file system
   * @return the corresponding containers in the workspace, or an empty array if none
   * @since 3.2
   */
  public IContainer[] findContainersForLocationURI(URI location);

  /**
   * Returns the handles to all the resources (workspace root, project, folder) in the workspace
   * which are mapped to the given URI. Returns an empty array if there are none.
   *
   * <p>If the {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is specified in the member flags, team
   * private members will be included along with the others. If the {@link
   * #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is not specified (recommended), the result will omit any
   * team private member resources.
   *
   * <p>If the {@link #INCLUDE_HIDDEN} flag is specified in the member flags, hidden members will be
   * included along with the others. If the {@link #INCLUDE_HIDDEN} flag is not specified
   * (recommended), the result will omit any hidden member resources.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * @param location a URI path into some file system
   * @param memberFlags bit-wise or of member flag constants ( {@link #INCLUDE_TEAM_PRIVATE_MEMBERS}
   *     and {@link #INCLUDE_HIDDEN}) indicating which members are of interest
   * @return the corresponding files in the workspace, or an empty array if none
   * @since 3.5
   */
  public IContainer[] findContainersForLocationURI(URI location, int memberFlags);

  /**
   * Returns the handles of all files that are mapped to the given path in the local file system.
   * Returns an empty array if there are none. The path should be absolute; a relative path will be
   * treated as absolute. The path segments need not be valid names. The resulting files may not
   * currently exist.
   *
   * <p>The result will omit any team private member and hidden resources. The result will omit
   * resources within team private member or hidden containers.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * @param location a path in the local file system
   * @return the corresponding files in the workspace, or an empty array if none
   * @since 2.1
   * @deprecated use {@link #findFilesForLocationURI(URI)} instead
   */
  @Deprecated
  public IFile[] findFilesForLocation(IPath location);

  /**
   * Returns the handles of all files that are mapped to the given URI. Returns an empty array if
   * there are none. The URI must be absolute; its path segments need not be valid names. The
   * resulting files may not currently exist.
   *
   * <p>The result will omit any team private member and hidden resources. The result will omit
   * resources within team private member or hidden containers.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * <p>This is a convenience method, fully equivalent to <code>
   * findFilesForLocationURI(location, IResource.NONE)</code>.
   *
   * @param location a URI path into some file system
   * @return the corresponding files in the workspace, or an empty array if none
   * @since 3.2
   */
  public IFile[] findFilesForLocationURI(URI location);

  /**
   * Returns the handles of all files that are mapped to the given URI. Returns an empty array if
   * there are none. The URI must be absolute; its path segments need not be valid names. The
   * resulting files may not currently exist.
   *
   * <p>If the {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is specified in the member flags, team
   * private members will be included along with the others. If the {@link
   * #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is not specified (recommended), the result will omit any
   * team private member resources.
   *
   * <p>If the {@link #INCLUDE_HIDDEN} flag is specified in the member flags, hidden members will be
   * included along with the others. If the {@link #INCLUDE_HIDDEN} flag is not specified
   * (recommended), the result will omit any hidden member resources.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * @param location a URI path into some file system
   * @param memberFlags bit-wise or of member flag constants ( {@link #INCLUDE_TEAM_PRIVATE_MEMBERS}
   *     and {@link #INCLUDE_HIDDEN}) indicating which members are of interest
   * @return the corresponding files in the workspace, or an empty array if none
   * @since 3.5
   */
  public IFile[] findFilesForLocationURI(URI location, int memberFlags);

  /**
   * Returns a handle to the workspace root, project or folder which is mapped to the given path in
   * the local file system, or <code>null</code> if none. If the path maps to the platform working
   * location, the returned object will be of type <code>ROOT</code>. If the path maps to a project,
   * the resulting object will be of type <code>PROJECT</code>; otherwise the resulting object will
   * be a folder (type <code>FOLDER</code>). The path should be absolute; a relative path will be
   * treated as absolute. The path segments need not be valid names; a trailing separator is
   * ignored. The resulting resource may not currently exist.
   *
   * <p>This method returns null when the given file system location is not equal to or under the
   * location of any existing project in the workspace, or equal to the location of the platform
   * working location.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * <p>Warning: This method ignores linked resources and their children. Since linked resources may
   * overlap other resources, a unique mapping from a file system location to a single resource is
   * not guaranteed. To find all resources for a given location, including linked resources, use the
   * method <code>findContainersForLocation</code>.
   *
   * @param location a path in the local file system
   * @return the corresponding project or folder in the workspace, or <code>null</code> if none
   */
  public IContainer getContainerForLocation(IPath location);

  /**
   * Returns a handle to the file which is mapped to the given path in the local file system, or
   * <code>null</code> if none. The path should be absolute; a relative path will be treated as
   * absolute. The path segments need not be valid names. The resulting file may not currently
   * exist.
   *
   * <p>This method returns null when the given file system location is not under the location of
   * any existing project in the workspace.
   *
   * <p>The result will also omit resources that are explicitly excluded from the workspace
   * according to existing resource filters.
   *
   * <p>Warning: This method ignores linked resources and their children. Since linked resources may
   * overlap other resources, a unique mapping from a file system location to a single resource is
   * not guaranteed. To find all resources for a given location, including linked resources, use the
   * method <code>findFilesForLocation</code>.
   *
   * @param location a path in the local file system
   * @return the corresponding file in the workspace, or <code>null</code> if none
   */
  public IFile getFileForLocation(IPath location);

  /**
   * Returns a handle to the project resource with the given name which is a child of this root. The
   * given name must be a valid path segment as defined by {@link IPath#isValidSegment(String)}.
   *
   * <p>Note: This method deals exclusively with resource handles, independent of whether the
   * resources exist in the workspace. With the exception of validating that the name is a valid
   * path segment, validation checking of the project name is not done when the project handle is
   * constructed; rather, it is done automatically as the project is created.
   *
   * @param name the name of the project
   * @return a project resource handle
   * @see #getProjects()
   */
  public IProject getProject(String name);

  /**
   * Returns the collection of projects which exist under this root. The projects can be open or
   * closed.
   *
   * <p>This is a convenience method, fully equivalent to <code>getProjects(IResource.NONE)</code>.
   * Hidden projects are <b>not</b> included.
   *
   * @return an array of projects
   * @see #getProject(String)
   * @see IResource#isHidden()
   */
  public IProject[] getProjects();

  /**
   * Returns the collection of projects which exist under this root. The projects can be open or
   * closed.
   *
   * <p>If the {@link #INCLUDE_HIDDEN} flag is specified in the member flags, hidden projects will
   * be included along with the others. If the {@link #INCLUDE_HIDDEN} flag is not specified
   * (recommended), the result will omit any hidden projects.
   *
   * @param memberFlags bit-wise or of member flag constants indicating which projects are of
   *     interest (only {@link #INCLUDE_HIDDEN} is currently applicable)
   * @return an array of projects
   * @see #getProject(String)
   * @see IResource#isHidden()
   * @since 3.4
   */
  public IProject[] getProjects(int memberFlags);
}
